#lang scribble/base

@(require "shared.rkt")

@;@title{How to Program Racket: a Style Guide}
@title{如何进行Racket编程：风格指南}
@author{Matthias Felleisen, Matthew Flatt, Robby Findler, Jay McCarthy}
@author{张恒源翻译}

@;@section-index{Style Guide}
@section-index{风格指南}

@; -----------------------------------------------------------------------------

@;{Since 1995 the number of ``repository contributors'' has grown from a small handful to
 three dozen and more. This growth implies a lot of learning 
 and the introduction of inconsistencies of programming styles. This document
 is an attempt leverage the former and to start reducing the latter. Doing so will
 help us, the developers, and our users, who use the open source code in
 our repository as an implicit guide to Racket programming.}
自1995年以来，“存储库贡献者”的数量已经从少数几个增加到三十多个。这种增长意味着大量的学习和编程风格不一致的引入。本文试图利用前者并开始减少后者。这样做将帮助我们、开发人员和我们的用户，他们使用我们存储库中的开源代码作为Racket编程的隐式指南。

@;{To help manage the growth our code and showcase good Racket style, we need
 guidelines that shape the contributions to the code base. These guidelines should
 achieve some level of consistency across the different portions of the
 code base so that everyone who opens files can easily find their way
 around.}
为了帮助管理代码的增长并展示良好的Racket风格，我们需要一些指导原则来塑造对代码库的贡献。这些指导原则应该在代码库的不同部分之间实现某种程度的一致性，以便打开文件的每个人都可以轻松找到解决方法。

@;{This document spells out the guidelines. They cover a range of topics, from
 basic work (commit) habits to small syntactic ideas like indentation and
 naming.}
这份文件阐明了指导方针。它们涵盖了一系列主题，从基本工作（提交）习惯到缩进和命名等小的语法思想。

@;{Many pieces of the code base don't live up to the guidelines yet.  Here is how
 we get started. When you start a new file, stick to the guidelines. If you need
 to edit a file, you will need to spend some time understanding its
 workings. If doing so takes quite a while due to inconsistencies with the
 guidelines, please take the time to fix (portions of) the file. After all, if
 the inconsistencies throw you off for that much time, others are likely to
 have the same problems. If you help fixing it, you reduce future
 maintenance time. Whoever touches the file next will be grateful to you.
 @emph{Do} run the test suites, and do @emph{not} change the behavior of
 the file.}
许多原始代码还没有达到准则的要求。下面是我们的开始。当你开始一个新的文件，坚持指导方针。如果你需要编辑一个文件，你需要花一些时间了解它的工作原理。如果由于与指南不一致而需要很长时间，请花时间修复（部分）文件。毕竟，如果前后矛盾让你耽误了那么长时间，其他人可能也会遇到同样的问题。如果你帮助修复它，你将减少未来的维护时间。下一个接触档案的人会感激你的。@emph{一定}运行测试套件，并一定@emph{不要}更改文件。

@;{Also, look over the commit messages. If you see problems with the code
 deltas, let the contributor know. If you see a bug fix without docs and
 tests, let the contributor know. Code should be viewed by more than one
 person because a second person is likely to catch logical mistakes,
 performance problems, and unintended effects.}
另外，查看提交消息。如果你看到代码增量有问题，请让贡献者知道。如果你看到没有文档和测试的bug修复，请让贡献者知道。代码应该由多个人查看，因为第二个人可能会捕获逻辑错误、性能问题和意外影响。

@;{@bold{Request} This document isn't complete and it isn't perfect. Consider
 it a call for improvements and suggestions.  If you have ideas, contact
 the first author via email. If your request gets ignored, appeal to all
 four authors.}
@bold{请求}此文档不完整，也不完美。把它看作是对改进和建议的呼吁。如果你有想法，请通过电子邮件联系第一作者。如果你的请求被忽略，请向四位作者上诉。

@;{@bold{Note} The recommendations in this style guide may not jibe with what
 you grew up with. (They conflict with some of the ideas that the primary
 author had about style.) But if you do write code that ends up in the
 Racket code base, please follow the recommendations here. If/when someone
 else works on your code, this person may ``fix'' your code if it isn't in
 compliance with the style guide.}
@bold{注意}本样式指南中的建议可能与你的成长环境格格不入。（它们与主要作者关于样式的一些想法相冲突）但是如果你写的代码最终出现在Racket代码库中，请遵循这里的建议。如果/当其他人处理你的代码时，如果不符合样式指南，此人可能会“修复”你的代码。

@; -----------------------------------------------------------------------------

@include-section["correct-maintain-speed.scrbl"]
@include-section["testing.scrbl"]
@include-section["unit.scrbl"]
@include-section["constructs.scrbl"]
@include-section["scribble.scrbl"]
@include-section["textual.scrbl"]
@include-section["some-performance.scrbl"]
@include-section["branch-and-commit.scrbl"]
@include-section["acknowledgment.scrbl"]

@include-section{todo.scrbl}
